3D Graphics Programming with QuickDraw 3D 1.5.4

Bounding in a View

As described in the chapters "Geometric Objects" and "Group Objects" , QuickDraw 3D provides routines that you can use to compute the bounding box and bounding sphere of an object or a group of objects in a model. Computing an object's bounding box or bounding sphere requires applying to it all the transforms in the current view transform stack. QuickDraw 3D provides routines that you must call before and after computing an object's bounds.

QuickDraw 3D also provides a routine that you can use to determine whether a bounding box is visible in a view. You might use that routine to avoid specifying portions of a model that aren't visible.

Q3View_StartBoundingBox

You can use the Q3View_StartBoundingBox function to start computing an object's bounding box.



 
TQ3Status Q3View_StartBoundingBox (

                     TQ3ViewObject view, 

                     TQ3ComputeBounds computeBounds);

view: A view.
computeBounds: A constant that specifies how the bounding box should be computed. See the following description for details.

DESCRIPTION

The Q3View_StartBoundingBox function begins the process of calculating a bounding box in the view specified by the view parameter. After calling Q3View_StartBoundingBox , you specify the model (for instance, by calling Q3Geometry_Submit ). When you have completely specified that model, you should call Q3View_EndBoundingBox to complete the bounding operation. The renderer attached to the specified view might need to reprocess the model data, so you should always call Q3View_StartBoundingBox and Q3View_EndBoundingBox in a bounding loop.

The computeBounds parameter determines the algorithm that QuickDraw 3D uses to calculate the bounding box. You should set computeBounds to one of these constants:



 
typedef enum TQ3ComputeBounds {

    kQ3ComputeBoundsExact,

    kQ3ComputeBoundsApproximate

} TQ3ComputeBounds;

If you set computeBounds to kQ3ComputeBoundsExact , the vertices of the geometric object are transformed into world space, and then the world space bounding box is computed from the transformed vertices. This method of calculating a bounding box produces the most precise bounding box but is slower than using the kQ3ComputeBoundsApproximate method.

If you set computeBounds to kQ3ComputeBoundsApproximate , a local bounding box is computed from the vertices of the geometric object, and then that bounding box is transformed into world space. The transformed bounding box is returned as the approximate bounding box of the geometric object. This method of calculating a bounding box is faster than using the kQ3ComputeBoundsExact method but produces a bounding box that might be larger than that computed by the exact method.

Q3View_EndBoundingBox

You can use the Q3View_EndBoundingBox function to stop computing an object's bounding box.



 
TQ3ViewStatus Q3View_EndBoundingBox (

                     TQ3ViewObject view, 

                     TQ3BoundingBox *result);

view: A view.
result: On exit, the bounding box for the objects specified in the bounding loop.

DESCRIPTION

The Q3View_EndBoundingBox function returns, as its function result, a view status value that indicates the current state of the bounding box calculation of the objects in the view specified by the view parameter. Q3View_EndBoundingBox returns one of these four values:



 
typedef enum TQ3ViewStatus {

    kQ3ViewStatusDone,

    kQ3ViewStatusRetraverse,

    kQ3ViewStatusError,

    kQ3ViewStatusCancelled

} TQ3ViewStatus;

If Q3View_EndBoundingBox returns kQ3ViewStatusDone , the bounding box calculation has completed. At that point, it is safe to exit your bounding loop. The result parameter contains the bounding box.

If Q3View_EndBoundingBox returns kQ3ViewStatusRetraverse , the bounding box calculation has not yet completed. You should respecify the model by reentering your bounding loop.

If Q3View_EndBoundingBox returns kQ3ViewStatusError , the bounding box calculation has failed. You should exit the bounding loop.

If Q3View_EndBoundingBox returns kQ3ViewStatusCancelled , the bounding box calculation has been canceled. You should exit the bounding loop.

SPECIAL CONSIDERATIONS

You should call Q3View_EndBoundingBox only if bounding box calculation is already occurring.

Q3View_StartBoundingSphere

You can use the Q3View_StartBoundingSphere function to start computing an object's bounding sphere.



 
TQ3Status Q3View_StartBoundingSphere (

                     TQ3ViewObject view, 

                     TQ3ComputeBounds computeBounds);

view: A view.
computeBounds: A constant that specifies how the bounding sphere should be computed. See the following description for details.

DESCRIPTION

The Q3View_StartBoundingSphere function begins the process of calculating a bounding sphere in the view specified by the view parameter. After calling Q3View_StartBoundingSphere , you specify the model (for instance, by calling Q3Geometry_Submit ). When you have completely specified that model, you should call Q3View_EndBoundingSphere to complete the bounding operation. The renderer attached to the specified view might need to reprocess the model data, so you should always call Q3View_StartBoundingSphere and Q3View_EndBoundingSphere in a bounding loop.

The computeBounds parameter determines the algorithm that QuickDraw 3D uses to calculate the bounding sphere. You should set computeBounds to one of these constants:



 
typedef enum TQ3ComputeBounds {

    kQ3ComputeBoundsExact,

    kQ3ComputeBoundsApproximate

} TQ3ComputeBounds;

If you set computeBounds to kQ3ComputeBoundsExact , the vertices of the geometric object are transformed into world space, and then the world space bounding sphere is computed from the transformed vertices. This method of calculating a bounding sphere produces the most precise bounding sphere but is slower than using the kQ3ComputeBoundsApproximate method.

If you set computeBounds to kQ3ComputeBoundsApproximate , a local bounding sphere is computed from the vertices of the geometric object, and then that bounding sphere is transformed into world space. The transformed bounding sphere is returned as the approximate bounding sphere of the geometric object. This method of calculating a bounding sphere is faster than using the kQ3ComputeBoundsExact method but produces a bounding sphere that might be larger than that computed by the exact method.

Q3View_EndBoundingSphere

You can use the Q3View_EndBoundingSphere function to stop computing an object's bounding sphere.



 
TQ3ViewStatus Q3View_EndBoundingSphere (

                     TQ3ViewObject view, 

                     TQ3BoundingSphere *result);

view: A view.
result: On exit, the bounding sphere for the objects specified in the bounding loop.

DESCRIPTION

The Q3View_EndBoundingSphere function returns, as its function result, a view status value that indicates the current state of the bounding sphere calculation of the objects in the view specified by the view parameter. Q3View_EndBoundingBox returns one of these four values:



 
typedef enum TQ3ViewStatus {

    kQ3ViewStatusDone,

    kQ3ViewStatusRetraverse,

    kQ3ViewStatusError,

    kQ3ViewStatusCancelled

} TQ3ViewStatus;

If Q3View_EndBoundingSphere returns kQ3ViewStatusDone , the bounding sphere calculation has completed. At that point, it is safe to exit your bounding loop. The result parameter contains the bounding sphere.

If Q3View_EndBoundingSphere returns kQ3ViewStatusRetraverse , the bounding sphere calculation has not yet completed. You should respecify the model by reentering your bounding loop.

If Q3View_EndBoundingSphere returns kQ3ViewStatusError , the bounding sphere calculation has failed. You should exit the bounding loop.

If Q3View_EndBoundingSphere returns kQ3ViewStatusCancelled , the bounding sphere calculation has been canceled. You should exit the bounding loop.

SPECIAL CONSIDERATIONS

You should call Q3View_EndBoundingSphere only if bounding sphere calculation is already occurring.

Q3View_IsBoundingBoxVisible

You can use the Q3View_IsBoundingBoxVisible function to determine whether a bounding box is visible in a view (that is, whether it lies in the viewing frustum).



 
TQ3Boolean Q3View_IsBoundingBoxVisible (

                     TQ3ViewObject view, 

                     const TQ3BoundingBox *bbox);

view: A view.
bbox: A bounding box.

DESCRIPTION

The Q3View_IsBoundingBoxVisible function returns, as its function result, a Boolean value that indicates whether the bounding box specified by the bbox parameter is visible in the view specified by the view parameter (kQ3True ) or is not visible (kQ3False ). Q3View_IsBoundingBoxVisible transforms the specified bounding box by the view's local-to-world transform and then determines whether the box lies in the viewing frustum.